home *** CD-ROM | disk | FTP | other *** search
/ Aminet 21 / Aminet 21 (1997)(GTI - Schatztruhe)[!][Oct 1997].iso / Aminet / util / cli / Find_v203.lha / Find.doc next >
Encoding:
Text File  |  1997-08-06  |  9.3 KB  |  294 lines
  1. Short:     File Finder (custom output and search)
  2. Author:    soenke@vapor.com (Sönke Tesch)
  3. Uploader:  soenke@vapor.com
  4. Type:      util/dir
  5. Replaces:  util/dir/Find.lha
  6. Keywords:  Find Search File
  7. Interface: CLI Shell
  8.  
  9. What`s it all about?
  10. ====================
  11.  
  12. This is probably the 10315th implementation of a File Finder. Anyway,
  13. I spend a full 2½ hours on the first version, even got some mails and
  14. therefore I like it best and and wrote a smarter update :)
  15.  
  16. Find will search in a directory and its subdirectories for objects
  17. matching a given pattern. You can say where, where not and how deep
  18. Find should search and if it should return only files or directories
  19. or both.
  20. The output is customizable similar to c:lists` LFORMAT option.
  21.  
  22. Find does not need any extra libraries nor does it feature a text viewer,
  23. database or coffee-machine. Want a fancy MUI user interface with fifty-
  24. thousand buttons? Go and look for another program, Find is CLI-only ;)
  25.  
  26.  
  27. How to use
  28. ==========
  29.  
  30.   Find PATTERN/A,LOCATIONS=ROOTDIR/M,DEPTH/N/K,DIRS/S,FILES/S,HEADER=STATS/S,
  31.        QUIET/S,PRINTSEARCHED/S,PRINTSKIPPED/S,LFORMAT=FORMAT/K
  32.  
  33.   PATTERN
  34.     Name of the file or directory you are looking for. This string may
  35.     also contain standard AmigaDOS wildcards like #,?,~ etc. Please see
  36.     your AmigaDOS manual for further details.
  37.     Find doesn`t support paths here (e.g. txt/Hello) and will return
  38.     error code 210 (Invalid Component Name) in this case.
  39.  
  40.   LOCATIONS (former ROOTDIR)
  41.     Find usually starts searching in the current directory and its sub-
  42.     directories. To let you search in other places the argument ROOTDIR
  43.     was defined in version 1. This argument has been extended and renamed
  44.     to LOCATIONS for Find².
  45.  
  46.     You may now give any number (well, actually 255;) of directories to
  47.     search in. These names may also contain wildcards.
  48.  
  49.     Furthermore you can exclude directories from the search by using a
  50.     - or a * as the first character. There`s a small difference between
  51.     the - and the *: * will exclude _any_ directory that matches the
  52.     given name regardless where it`s located. Like PATTERN * works with
  53.     path-less directory names only (i.e. with "blabla" but not with
  54.     "txt/blabla").
  55.  
  56.     NOTE:
  57.       To exclude a directory means to exclude all its subdirectories, too!
  58.       However, you may of course include a subdirectory of an excluded
  59.       directory.
  60.  
  61.     Take the following directory structure as an example:
  62.     ----------------------------------------------------------------------
  63.  
  64.     1> dir all ;; current directory is Find
  65.            txt (dir)
  66.                 test (dir)
  67.                   test2
  68.              Find.mod                         Find.mod_2.0
  69.              Test.mod
  70.            obj (dir)
  71.              Find.obj                         Test.obj
  72.            testdir1 (dir)
  73.                 testdir2 (dir)
  74.                   test1
  75.         cmc.opt                          Find
  76.         Find.lha                         find.mtx
  77.         find.readme                      test
  78.         test.mtx
  79.  
  80.     1> find test?
  81.     txt/test/test2
  82.     testdir1/testdir2/test1
  83.  
  84.     1> find test? test#? printsearched
  85.     Scanning testdir1
  86.     Scanning testdir1/testdir2
  87.     testdir1/testdir2/test1
  88.  
  89.     1> find #?st(?|%|.m[a-y]d)  ;; AmigaDOS wildcards are powerfull! :)
  90.     txt/test
  91.     txt/test/test2
  92.     txt/Test.mod
  93.     txt/testdir1/testdir2/test1
  94.     test
  95.  
  96.     1> find test? *test#? printsearched printskipped
  97.     Scanning txt
  98.     Skipped txt/test
  99.     Scanning obj
  100.     Skipped testdir1
  101.  
  102.     1> find test? -txt/test#? printskipped
  103.     Skipped txt/test
  104.     testdir1/testdir2/test1
  105.  
  106.     1> find test? -test#? printskipped
  107.     txt/test/test2
  108.     Skipped testdir1
  109.  
  110.     1> find test? *txt/test#? printskipped
  111.     txt/test/test2
  112.     testdir1/testdir2/test1
  113.     ;; didn`t work: * doesn`t support paths
  114.  
  115.     ----------------------------------------------------------------------
  116.  
  117.     + is also supported as first character. This will do the exactly
  118.     same as if you omit it.
  119.  
  120.     NOTE:
  121.       · If you have a name that starts with +, - or * you`ll have to
  122.         put one of +, - or * in front of it in order to work correctly!
  123.       · Use "-Mr Spacey:blabla" instead of -"Mr Spacey:blabla"!
  124.  
  125.   DEPTH
  126.     Maximum level of sub-directories Find will search in. The current
  127.     directory (or LOCATION if used) is level 0.
  128.  
  129.       find EggPaint dh0: depth 0
  130.  
  131.     will thus search only in the the root of dh0:.
  132.     The default is unlimited.
  133.  
  134.     NOTE:
  135.       If Find finds a matching link it will return the path and filename
  136.       of the file the link points to, _not_ of the link! Therefore you
  137.       may get files very deep in your directory tree although you set
  138.       DEPTH to 1 or even 0. Not my fault, this is the behaviour of the
  139.       NameFromLock() function in dos.library..:|
  140.  
  141.   DIRS
  142.     Find returns only directories matching PATTERN.
  143.  
  144.   FILES
  145.     Find returns only files matching PATTERN.
  146.  
  147.   HEADER (former STATS)
  148.     Find will print some extra information after the search, e.g.
  149.  
  150.       1 files and 5 directories in 2 of 7 places (0 skipped)
  151.  
  152.     This obviously means Find found 1 matching file and 5 matching
  153.     directories in 2 directories. Find searched in a total of 7
  154.     directories and skipped 0.
  155.  
  156.   QUIET
  157.     By default Find prints some information about where it is currently
  158.     looking for matching objects to the Shell window. This output can be
  159.     switched off by setting QUIET.
  160.     QUIET doesn`t affect output of PRINTSEARCHED and PRINTSKIPPED, so
  161.     if both of these are set, QUIET is actually useless.
  162.  
  163.     Setting QUIET may speed-up the search significantly, partly due to
  164.     the fact that text output is relativly slow on some configurations.
  165.  
  166.   PRINTSEARCHED
  167.     Find prints a list of the directories it searched in.
  168.  
  169.   PRINTSKIPPED
  170.     Same as PRINTSEARCHED but will print a list of the directories it
  171.     skipped.
  172.  
  173.   LFORMAT or FORMAT
  174.     This is similar to the c:list argument LFORMAT. The given string is
  175.     written to the output for every matching object. The following commands
  176.     are supported:
  177.  
  178.       %s - inserts full path and name of the object
  179.       %n - inserts the name of the object
  180.       %p - inserts the _full_ path of the object. This is different to
  181.            c:lists` %p which prints the path relative to the current
  182.            directory.
  183.  
  184.     Example:
  185.  
  186.       Find EggPaint#? format "Found the magnificent %n in %p."
  187.  
  188.     might output
  189.  
  190.       Found the magnificent EggPaint in My First Disk:Gfx.
  191.  
  192.     NOTE:
  193.       Find² now automatically appends a carriage return to the end of
  194.       the string. This is different to version 1.
  195.  
  196.  
  197. Stop-That-Work® Option
  198. ======================
  199.  
  200.   Pressing ctrl-c will do a full stop, ctrl-e will stop the current
  201.   directory scan only.
  202.  
  203.  
  204. Return Codes
  205. ============
  206.  
  207.   Code  Level Meaning
  208.      0        no matching objects found
  209.      5  warn  object(s) found - number is in local variable Result2
  210.     10  error one or more LOCATIONs not found
  211.     20  fail  Usually out-of-memory condition
  212.     21    "   Arguments didn`t match
  213.     22    "   Wildcards in PATTERN are not valid or a path was given
  214.     23    "   Either wildcard problem or something went wrong while
  215.               searching for matching directories
  216.     30    "   Virus Warning
  217.  
  218.  
  219. Copyright
  220. =========
  221.  
  222.   Find, Find.readme and Find.doc:
  223.    Copyright 1997 by Sönke Tesch
  224.    All Rights Reserved.
  225.  
  226.   You may re-distribute the archive as long as no file is removed or
  227.   changed.
  228.   Find has to be distributed for FREE, any other kind of distribution
  229.   without my written permission is not allowed. However, this is not
  230.   the case for any AmiNet-CD. Others please feel free to ask.
  231.   I do not give any guarantee for the quality and usefulness of Find
  232.   nor that it works as described or fits particular needs.
  233.  
  234.  
  235. Contact
  236. =======
  237.  
  238.   Comments, suggestions, bug-reports and Hey-I-use-it!-mails are
  239.   always welcome! Just write to <soenke@vapor.com>.
  240.  
  241.  
  242. Those finer details..
  243. =====================
  244.  
  245.   Find features a simple build-in virus self-protection.
  246.  
  247.   Find is written using Cyclone Modula-2 by Marcel Timmermans.
  248.   The source is available on request, just ask.
  249.  
  250.   Find is still smaller than this document :)
  251.  
  252.  
  253. History
  254. =======
  255.  
  256.   06-Aug-97 2.03 ¤ bugfix in DoDir()
  257.                  + even more optimizations
  258.                  ¤ viruscheck wasn`t enabled (boo:)
  259.                  a released on Aminet
  260.  
  261.   21-Jul-97 2.02 ¤ Fixed bug in output routine (didn`t clear lines)
  262.                  + various optimizations to get size below the magic 5k
  263.                  + returns error if PATTERN is a path
  264.                  ¤ (hopefully) solved problem that ctrl-e didn`t work
  265.                    from time to time
  266.                  a released on Aminet
  267.  
  268.   10-Jul-97 2.01 + Total number of found objects returned in Result2
  269.                  + Fixed return codes so that they better match the
  270.                    system "standards"
  271.                  ¤ Although documented it wouldn`t QUIET did suppress
  272.                    output of PRINTSKIPPED and PRINTSEARCHED
  273.                  + Non-existing LOCATIONs return error code 10
  274.  
  275.   09-Jul-97 2.00 + added * to control search
  276.                  + FORMAT now supports %n and %p
  277.                  + PRINTSKIPPED & PRINTSEARCHED
  278.                  a non-public gamma release
  279.  
  280.   08-Jul-97 2.00 + search locations may be controlled by +, -
  281.  
  282.   19-May-97 1.00 a Version 1.00 on Aminet
  283.  
  284.  
  285. Have fun,
  286.   soenk.e
  287.  
  288.  
  289. --
  290. Amiga Translators Organization * Main & German Admin, Ex-Human Listserver
  291. ato    : ato-admin-de@ato.vapor.com & ato-admin@ato.vapor.com
  292. private: soenke@vapor.com
  293.  
  294.